home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / AIncludes / Translation.a < prev    next >
Encoding:
Text File  |  1998-08-17  |  12.8 KB  |  362 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        Translation.a
  3. ;
  4. ;    Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5. ;
  6. ;    Version:    Technology:    Macintosh Easy Open 1.1
  7. ;                Release:    Universal Interfaces 3.2
  8. ;
  9. ;    Copyright:    © 1991-1998 by Apple Computer, Inc., all rights reserved.
  10. ;
  11. ;    Bugs?:        For bug reports, consult the following page on
  12. ;                the World Wide Web:
  13. ;
  14. ;                    http://developer.apple.com/bugreporter/
  15. ;
  16. ;
  17.     IF &TYPE('__TRANSLATION__') = 'UNDEFINED' THEN
  18. __TRANSLATION__ SET 1
  19.  
  20.     IF &TYPE('__MACTYPES__') = 'UNDEFINED' THEN
  21.     include 'MacTypes.a'
  22.     ENDIF
  23.     IF &TYPE('__FILES__') = 'UNDEFINED' THEN
  24.     include 'Files.a'
  25.     ENDIF
  26.     IF &TYPE('__COMPONENTS__') = 'UNDEFINED' THEN
  27.     include 'Components.a'
  28.     ENDIF
  29.     IF &TYPE('__TRANSLATIONEXTENSIONS__') = 'UNDEFINED' THEN
  30.     include 'TranslationExtensions.a'
  31.     ENDIF
  32.  
  33. ;  enumerated types on how a document can be opened
  34. ; typedef short                         DocOpenMethod
  35.  
  36.  
  37. domCannot                        EQU        0
  38. domNative                        EQU        1
  39. domTranslateFirst                EQU        2
  40. domWildcard                        EQU        3
  41. ;  0L terminated array of OSTypes, or FileTypes
  42. TypesBlock                RECORD 0
  43. elements                 ds.l    64
  44. sizeof                     EQU *                    ; size:   $100 (256)
  45.                         ENDR
  46.  
  47.  
  48. ; typedef OSType *                        TypesBlockPtr
  49.  
  50. ;  Progress dialog resource ID
  51.  
  52. kTranslationScrapProgressDialogID EQU    -16555
  53. ;  block of data that describes how to translate
  54. FileTranslationSpec        RECORD 0
  55. componentSignature         ds.l    1                ; offset: $0 (0)
  56. translationSystemInfo     ds.l    1                ; offset: $4 (4)
  57. src                         ds        FileTypeSpec    ; offset: $8 (8)
  58. dst                         ds        FileTypeSpec    ; offset: $1C (28)
  59. sizeof                     EQU *                    ; size:   $30 (48)
  60.                         ENDR
  61. FileTranslationSpecArray RECORD 0
  62. elements                 ds.b    1 * FileTranslationSpec.sizeof
  63. sizeof                     EQU *                    ; size:   $30 (48)
  64.                         ENDR
  65.  
  66.  
  67. ; typedef FileTranslationSpecArray *    FileTranslationSpecArrayPtr
  68.  
  69. ; typedef FileTranslationSpecArrayPtr *    FileTranslationSpecArrayHandle
  70.  
  71.  
  72. ; *****************************************************************************************
  73. ;* 
  74. ;*   GetFileTypesThatAppCanNativelyOpen
  75. ;* 
  76. ;*  This routine returns a list of all FileTypes that an application can open by itself
  77. ;* 
  78. ;*  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  79. ;*             appSignature        signature (creator) of application
  80. ;*             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  81. ;* 
  82. ;*  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  83. ;
  84.  
  85. ;
  86. ; pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  87. ;
  88.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  89.         Macro
  90.         _GetFileTypesThatAppCanNativelyOpen
  91.             moveq               #28,D0
  92.             dc.w                $ABFC
  93.         EndM
  94.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  95.         IMPORT_CFM_FUNCTION GetFileTypesThatAppCanNativelyOpen
  96.     ENDIF
  97.  
  98. ; *****************************************************************************************
  99. ;* 
  100. ;*  ExtendFileTypeList
  101. ;* 
  102. ;*  This routine makes a new list of file types that can be translated into a type in the given list
  103. ;*  Used by StandardFile
  104. ;* 
  105. ;*  Enter:    originalTypeList        pointer to list of file types that can be opened
  106. ;*             numberOriginalTypes        number of file types in orgTypeList
  107. ;*              extendedTypeList        pointer to a buffer to be filled with file types
  108. ;*             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  109. ;* 
  110. ;*  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  111. ;*             numberExtendedTypes        number of file types put in extendedTypeList
  112. ;
  113.  
  114. ;
  115. ; pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  116. ;
  117.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  118.         Macro
  119.         _ExtendFileTypeList
  120.             moveq               #9,D0
  121.             dc.w                $ABFC
  122.         EndM
  123.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  124.         IMPORT_CFM_FUNCTION ExtendFileTypeList
  125.     ENDIF
  126.  
  127.  
  128. ; *****************************************************************************************
  129. ;* 
  130. ;* 
  131. ;*  This routine checks if a file can be opened by a particular application.
  132. ;*  If so, it returns if it needs to be translated first, and if so then how.
  133. ;*  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  134. ;*  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  135. ;* 
  136. ;*  Enter:    targetDocument        document to check if it can be opened
  137. ;*             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  138. ;*             appSignature        signature (creator) of application to open doc
  139. ;*             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  140. ;*             onlyNative            whether to consider if document can be translated before opening
  141. ;*             howToOpen            pointer to buffer in which to put how the document can be opened
  142. ;*             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  143. ;* 
  144. ;*  Exit:    howToOpen            whether file needs to be translated to be read
  145. ;*             howToTranslate        if file can be translated, buffer filled in with how to translate
  146. ;*             returns                noErr, noPrefAppErr
  147. ;
  148.  
  149. ;
  150. ; pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  151. ;
  152.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  153.         Macro
  154.         _CanDocBeOpened
  155.             moveq               #30,D0
  156.             dc.w                $ABFC
  157.         EndM
  158.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  159.         IMPORT_CFM_FUNCTION CanDocBeOpened
  160.     ENDIF
  161.  
  162.  
  163. ; *****************************************************************************************
  164. ;* 
  165. ;*  GetFileTranslationPaths
  166. ;* 
  167. ;*  This routine returns a list of all ways a translation can occure to or from a FileType.
  168. ;*  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  169. ;* 
  170. ;*  Enter:    srcDoc            source file or NULL for all matches
  171. ;*             dstDoc            destination FileType or 0 for all matches
  172. ;*             maxResultCount
  173. ;*             resultBuffer
  174. ;*  Exit:    number of paths
  175. ;
  176.  
  177. ;
  178. ; pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  179. ;
  180.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  181.         Macro
  182.         _GetFileTranslationPaths
  183.             moveq               #56,D0
  184.             dc.w                $ABFC
  185.         EndM
  186.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  187.         IMPORT_CFM_FUNCTION GetFileTranslationPaths
  188.     ENDIF
  189.  
  190. ; *****************************************************************************************
  191. ;* 
  192. ;*  GetPathFromTranslationDialog
  193. ;* 
  194. ;*  This routine, with a given document, application, and a passed typelist will display the
  195. ;*  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  196. ;*  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  197. ;*  The routine returns the translation path information.
  198. ;* 
  199. ;*  Enter:    theDocument            FSSpec to document to open
  200. ;*             theApplication        FSSpec to application to open document
  201. ;*             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  202. ;*                                 you would like the documented translated to.  Order most perferred
  203. ;*                                 to least.
  204. ;* 
  205. ;*  Exit:    howToOpen            Translation method needed to open document
  206. ;*             howToTranslate        Translation specification
  207. ;*             returns                Any errors that might occur.
  208. ;
  209.  
  210. ;
  211. ; pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  212. ;
  213.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  214.         Macro
  215.         _GetPathFromTranslationDialog
  216.             moveq               #55,D0
  217.             dc.w                $ABFC
  218.         EndM
  219.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  220.         IMPORT_CFM_FUNCTION GetPathFromTranslationDialog
  221.     ENDIF
  222.  
  223.  
  224. ; *****************************************************************************************
  225. ;* 
  226. ;*   TranslateFile
  227. ;* 
  228. ;*  This routine reads a file of one format and writes it to another file in another format. 
  229. ;*  The information on how to translated is generated by the routine CanDocBeOpened.
  230. ;*  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  231. ;*  The destination file must not exist.  It is created by this routine.  
  232. ;* 
  233. ;*  Enter:    sourceDocument            input file to translate
  234. ;*             destinationDocument        output file of translation
  235. ;*             howToTranslate            pointer to info on how to translate
  236. ;*  Exit:    returns                    noErr, badTranslationSpecErr 
  237. ;
  238.  
  239. ;
  240. ; pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  241. ;
  242.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  243.         Macro
  244.         _TranslateFile
  245.             moveq               #12,D0
  246.             dc.w                $ABFC
  247.         EndM
  248.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  249.         IMPORT_CFM_FUNCTION TranslateFile
  250.     ENDIF
  251.  
  252. ; *****************************************************************************************
  253. ;* 
  254. ;*   GetDocumentKindString
  255. ;* 
  256. ;*  This routine returns the string the Finder should show for the "kind" of a document
  257. ;*  in the GetInfo window and in the kind column of a list view.  
  258. ;* 
  259. ;*  Enter:    docVRefNum        The volume containing the document
  260. ;*             docType            The catInfo.fdType of the document
  261. ;*             docCreator        The catInfo.fdCreator of the document
  262. ;*             kindString        pointer to where to return the string
  263. ;* 
  264. ;*  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  265. ;*             returns            noErr, or afpItemNoFound if kind could not be determined
  266. ;
  267.  
  268. ;
  269. ; pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  270. ;
  271.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  272.         Macro
  273.         _GetDocumentKindString
  274.             moveq               #22,D0
  275.             dc.w                $ABFC
  276.         EndM
  277.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  278.         IMPORT_CFM_FUNCTION GetDocumentKindString
  279.     ENDIF
  280.  
  281. ; *****************************************************************************************
  282. ;* 
  283. ;*  GetTranslationExtensionName
  284. ;* 
  285. ;*  This routine returns the translation system name from a specified TranslationSpec
  286. ;* 
  287. ;*  Enter:    translationMethod    The translation path to get the translation name from
  288. ;* 
  289. ;*  Exit:    extensionName        The name of the translation system
  290. ;*             returns                Any errors that might occur
  291. ;
  292.  
  293. ;
  294. ; pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  295. ;
  296.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  297.         Macro
  298.         _GetTranslationExtensionName
  299.             moveq               #54,D0
  300.             dc.w                $ABFC
  301.         EndM
  302.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  303.         IMPORT_CFM_FUNCTION GetTranslationExtensionName
  304.     ENDIF
  305.  
  306.  
  307. ; *****************************************************************************************
  308. ;* 
  309. ;*  GetScrapDataProcPtr
  310. ;* 
  311. ;*  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  312. ;*  get the data to be translated.  The first call TranslateScrap will make to this is to
  313. ;*  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  314. ;*  with a list all the formats that you have available to be translated, and the length of each.
  315. ;*  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  316. ;*  the formats that 'fmts' list said was available.
  317. ;* 
  318. ;*  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  319. ;*             dataH                    Handle in which to put the requested data
  320. ;*             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  321. ;*             
  322. ;*  Exit:    dataH                    Handle is resized and filled with data in requested format
  323. ;
  324.  
  325. ; typedef GetScrapDataUPP                 GetScrapData
  326.  
  327. ; *****************************************************************************************
  328. ;* 
  329. ;*  TranslateScrap
  330. ;* 
  331. ;*  This routine resizes the destination handle and fills it with data of the requested format.
  332. ;*  The data is generated by translated one or more source formats of data supplied by
  333. ;*  the procedure srcDataGetter.  
  334. ;*  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  335. ;*  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  336. ;* 
  337. ;*  Enter:    sourceDataGetter            Pointer to routine that can get src data
  338. ;*             sourceDataGetterRefCon        Extra parameter for dataGetter
  339. ;*             destinationFormat            Format of data desired
  340. ;*             destinationData                Handle in which to store translated data
  341. ;*             
  342. ;*  Exit:    dstData                        Handle is resized and filled with data in requested format
  343. ;
  344.  
  345. ;
  346. ; pascal OSErr TranslateScrap(GetScrapDataUPP sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  347. ;
  348.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  349.         Macro
  350.         _TranslateScrap
  351.             moveq               #14,D0
  352.             dc.w                $ABFC
  353.         EndM
  354.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  355.         IMPORT_CFM_FUNCTION TranslateScrap
  356.     ENDIF
  357.  
  358.  
  359.  
  360.     ENDIF ; __TRANSLATION__ 
  361.  
  362.